<html>
<head>
<link href="doc.css" rel="stylesheet" type="text/css">
<title>aiEditor</title>
</head>
<body>
<h2>aynHTML Editor :: wysiwyg HTML editor for IE5.5+</h2>
	<ul>
		<li><a href="#name">NAME</a></li>
		<li><a href="#version">VERSION</a></li>
		<li><a href="#synopsis">SYNOPSIS</a></li>
		<li><a href="#description">DESCRIPTION</a></li>
		<li><a href="#description">PREREQUISITES</a></li>
		<li><a href="#properties">PROPERTIES</a></li>
		<li><a href="#methods">METHODS</a></li>
		<li><a href="#events">EVENTS</a></li>
		<li><a href="#troubleshooting">TROUBLESHOOTING</a></li>
		<ul>
			<li type="disc">Apache</li>
			<li type="disc">PHP</li>
			<li type="disc">IE security settings</li>
		</ul>
		<li><a href="#todo">TO DO</a></li>
		<li><a href="#author">AUTHOR</a></li>
		<li><a href="#homepage">HOMEPAGE</a></li>
		<li><a href="#copyleft">COPYLEFT</a></li>
	</ul>
<hr><h1><a name="name">NAME</a></h1>
<p>aynHTML Editor :: wysiwyg HTML editor for IE5.5+</p>
<hr><h1><a name="version">VERSION</a></h1>
<p>Version 0.20b (beta) - 2003-05-05</p>
<hr><h1><a name="synopsis">SYNOPSIS</a></h1>

<pre>
&lt;html xmlns:AI&gt;
	&lt;head&gt;
		&lt;?import namespace="AI" implementation="aiEditor.htc" /&gt;
	&lt;/head&gt;
	&lt;body&gt;
		&lt;AI:aiEditor id="aiEditor"
			stylesheet="external.css"
			save_method="custom"&gt;
			&lt;p align="center"&gt;&lt;b&gt;Welcome to aynHTML Editor !&lt;/b&gt;&lt;/p&gt;
		&lt;/AI:aiEditor&gt;
		&lt;script language="javascript"&gt;
			onload = function() {
				aiEditor.append( 'id', 1 );
			}
			
			aiEditor.onsave = do_something;
			
			function do_something( e ) {
				alert( e.content );
			}
		&lt/script&gt;
	&lt;/body&gt;
&lt;/html&gt;
</pre>
<hr><h1><a name="description">DESCRIPTION</a></h1>
<p>The aynHTML editor is a wysiwyg HTML editor for use with IE5.5 and above.</p>
<p>In order to use the editor on a web page, just insert a tag like the one in the synopsis in your HTML.
	Note that the xmlns declaration in the &lt;html&gt; tag is required to make it work.
	The different attributes of the &lt;AI:aiEditor&gt; tag control the behaviour of the editor.</p>
<p>The content between the editor tags is loaded into the editor window, which makes it easy to insert dynamic content using a scripting language like PHP or ASP.
	Alternatively, you can load content through xml or html, or customize the way content is loaded and saved.</p>
<hr><h1><a name="prerequisites">PREREQUISITES</a></h1>
<p>The editor makes use of custom elements implemented as behaviours.  Only Internet Explorer 5.5 and higher support this as of this date.</p>
<p>The file upload component makes use of the ADO Stream object, which limits its use to the Win32 platform.
	The ADO Stream object ships as part of Microsoft's Data Access Components ( MDAC ) version 2.5 and higher.
	Windows 2000 en Millenium ship with MDAC v2.5, Windows XP ships with MDAC 2.7, and thus do not necessite further downloads.</p>
<p>For Windows 95 and some versions of Windows 98, it is necessary to install DCOM95, respectively DCOM98 first, which can be downloaded at
	<a href="http://www.microsoft.com/com/resources/downloads.asp">http://www.microsoft.com/com/resources/downloads.asp</a>.
	The latest MDAC version can be found at <a href="www.microsoft.com/data">http://www.microsoft.com/data</a>.</p>
<hr><h1><a name="properties">PROPERTIES</a></h1>
	<dl>
		<dt>id
		<dd><p>Id of the object, so it can be referenced in script in the containing document.</p>
		<dt>color
		<dd><p>The color of the editor's chrome.
		Please note that this property isn't fully implemented yet, so dialog boxes and buttons may not appear the way you want.</p>
		<dt>content
		<dd><p>This property gets or sets the editor's content.
		You could use as an attribute in the editor's html tag, though why should you, as there are easier methods to control the editor's content.
		This attribute is mainly meant for use in the editor's <b>onbeforeload</b> and <b>onopen</b> events.  See the description of the <b>onbeforeload</b> event for an example.</p>
		<dt>emo_get
		<dd><p>The emo_get property holds an absolute or relative url to an xml file containing the emoticons.
		If you choose to use a relative path, please note that the path is relative to the editor, not to its containing page.
		So if your index.html file resides in /, your aiEditor.htc file resides in /aynhtml/, 
		and your emotes url is a file called emotes.xml residing in /aynhtml/xml/, you should use</p>
<pre>
emo_get = "xml/emotes.xml"
path = "aynhtml/"
</pre>
		<p>The elements in the xml file should contain a <b>href</b> attribute pointing to the location of the emoticon.
		Optionally, the <b>name</b> attribute is used in the 'alt' attribute of the image.</p>
		<p>If you don't want to use the emoticons, simply omit this property.</p>
		<dt>emo_path
		<dd><p><b>deprecated in v0.18b - use emo_get instead</b></p>
		<p>The path where the emoticons used by the editor can be found.
		This path is relative to the path of the editor component.
		If you don't want to use the emoticons, simply omit this property.</p>
		<dt>font
		<dd><p>A comma-separated list of fonts that can be chosen in the editor.
		If this property is not supplied, the font dropdown of the editor isn't shown.</p>
		<dt>font_size
		<dd><p>A comma-separated list of the font sizes the user can choose from.  Font size will be applied in pixels.
		As with the font property, omitting it will cause the editor to hide the dropdown.</p>
		<dt>height
		<dd><p>The height of the editor.</p>
		<dt>hide_btn
		<dd><p>This property accepts a comma separated list of buttons to hide from the user interface.</p>
		<p>Values: 'link' | 'save' | 'color' | 'anchor' | 'table' | 'image' | 'emote' | 'word' | 'open'.</p>
		<dt>link_get
		<dd><p>The editor builds a list of internal links - useful for use within a CMS - by querying an xml file through HTTP.
		The link_get property holds the absolute or relative url of this file.
		If you choose to use a relative path, please note that the path is relative to the editor, not to its containing page.
		See the example under the <b>emo_get</b> property for this.</p>
		<p>Note that as the editor uses the http protocol to load the xml, this feature will not work locally.  The xml file needs to be reachable through http.</p>
		<p>The editor builds a nested link tree from the xml file's contents.
		Element names and element content are ignored, only the attributes <b>name</b> and <b>href</b> of each element are used, respectively as the name shown in the tree and the hyperlink which is generated.</p>
		<p>For more info, see the <a href="../sample/text/links.xml">sample links file</a> included, or view the docs of the <a href="aiTree.html">aiTree component</a>.</p>
		<dt>load_method
		<dd><p>This property controls how the editor's content is loaded.</p>
		<p>Choosing <b>inline</b> tells the editor to use whatever is written between the &lt;AI:aiEditor&gt; and &lt;/AI:aiEditor&gt; tags for content.
		The 'html' option will send a request to the url indicated in the <b>load_url</b> property and paste the response into the editor.
		The 'xml' option gives you the opportunity of adding other fields besides the content, such as a document id.  Specification to follow.
		The 'custom' option finally has no action associated with it, but allows you to control the editor's content through the <b>onbeforeload</b> event.</p>
		<p>Values: 'inline' ( default ) | 'html' | 'xml' | 'custom'.</p>
		<dt>open_method
		<dd><p>This property controls the editor's behaviour when the 'open' button is pressed, or the <b>open()</b> method is called.</p>
		<p>The default action is to reload the content as specified in the <b>load_method</b> property.
		If <b>load_method</b> is 'inline', the editor's default action is to refresh the page.
		Choosing 'custom' for this property allows you to script the editor's behaviour via the <b>onopen</b> event.</p>
		<p>If you set the <b>load_method</b> to 'custom', the editor's default <b>open()</b> action is to generate an <b>onbeforeload</b> event.
		For a different behaviour, set the <b>open_method</b> property to 'custom', and add the necessary code to the <b>onopen</b> handler.</p>
		<p>Values: 'default' ( default ) | 'custom'.</p>
		<dt>palette
		<dd><p>This property defines which of the available color palettes will be shown in the color picker.<br>
		Color palettes and colors are defined in <b>colors.xml</b>, and are of the following format:</p>
<pre>
&lt;colors&gt;
	&lt;range value="web" name="Web Safe Colors"&gt;
		&lt;color value="white" /&gt;
	&lt;/range&gt;
	&lt;range value="custom" name="Custom Colors"&gt;
		&lt;color value="#ffea20" /&gt;
	&lt;/range&gt;
&lt;/colors&gt;
</pre>
		<p>The <b>value</b> attribute of the range element stands for the palette which can be chosen through the editor's palette property.<br>
		The <b>name</b> attribute is used in the title bar of the color picker.</p>
		<p>Values: 'web' | 'system' | 'custom' ( default: 'web, system' )</p>
		<dt>path
		<dd><p>Use this property in case the editor resides in a directory that differs from its embedding page.
		You'll also need to modify the import statement.  For example:</p>
<pre>&lt;html xmlns:AI&gt;
	&lt;head&gt;
		&lt;?import namespace="AI" implementation="editor/aiEditor.htc" /&gt;
	&lt;/head&gt;
	&lt;body&gt;
		&lt;AI:aiEditor id="aiEditor" path="editor/" /&gt;
	&lt;/body&gt;
&lt;/html&gt;</pre>
		<dt>pic_get
		<dd><p>The absolute or relative url of the file that generates a list of available images.
		The file needs to be an xml document similar in structure to the links file.
		If you choose to use a relative path, please note that the path is relative to the editor, not to its containing page.
		See the example under the <b>emo_get</b> property for this.</p>
		<p>For more info, see the <a href="../sample/text/images.xml">sample images file</a> included, or view the docs of the <a href="aiTree.html">aiTree component</a>.</p>
		<dt>pic_put
		<dd><p>The url to which uploaded images are sent.  Typically, this file will be an ASP, PHP or CGI script.
		Uploaded images are sent as an xml file of the following form:</p>
<pre>&lt;root xmlns:dt="urn:schemas-microsoft-com:datatypes"&gt;
	&lt;file name="Holiday Pics: me and my dawg"
		folder="pics/holiday/spain"
		href="c:/my pictures/lloret/dog.jpg"
		dt:dt="bin.base64"
	&gt;
		[base 64 encoded binary content of the file]
	&lt;/file&gt;
&lt;/root&gt;</pre>
		<p>The <b>href</b> attribute contains the full local filename of the uploaded file.
		The <b>folder</b> attribute holds the folder hierarchy selected in the folder dropdown.
		The <b>name</b> attribute contains the text the user typed in the description field.</p>
		<p>The folder names may or may not correspond to a physical hierarchy on the webserver.
		In the second case, you can use the folder names to build a virtual hierarchy for the end user.
		It's up to you.  However, as there is no obligatory link between the folder names and a file's url, it falls to the upload script to return this info to the editor.
		The upload script should output an xml string of this form, where <b>href</b> can be either an absolute or a fully qualified url:</p>
<pre>&lt;root&gt;
	&lt;file href="/upload/usr_12/pics/pic0013.jpg" /&gt;
&lt;/root&gt;</pre>
		<dt>save_method
		<dd><p>The method by which the contents of the editor will be saved.
		The editor knows two built-in values, "form" and "xml".<br>
		Choosing "form" will generate a traditional http request with url encoded form fields.
		The content of the editor is copied to the "aiContent" form field.
		Choosing "xml" makes use of the MS XML component to generate an xml string.
		The content of the editor is held in the text of the "content" element.
		In both cases, the contents are posted to the url specified in the save_url property.<br>
		<br>
		The editor generates an onsave event, which contains the HTML in its <b>content</b> property.  This is especially useful if
		you want to do your own save processing by setting the <b>save_method</b> to 'custom'.
		See the synopsis for an example.<br>
		<br>
		Values: 'form' (default) | 'xml' | 'custom'.
		</p>
		<dt>save_url
		<dd><p>The url to which the contents of the editor are posted.
		Depending on the save_method chosen, this file should either read in the posted xml, or the urlencoded form values.</p>
		<dt>style_import
		<dd><p>This property controls whether the editor will search its embedding document for <b>&lt;style&gt;</b> and <b>&lt;link&gt;</b> tags.<br>
		CSS classes specified in those tags will be imported in the styles dropdown, and can be applied to the editor's content.</p>
		<p>Currently, only simple classes like <b>.title</b> are imported into the dropdown.<br>
		Element-specific ones like <b>p.important { }</b> or nested classed like <b>p b { }</b> affect the editor's content, but cannot be selected as a style to apply.<br>
		This will change in a future release.  Element-specific classes will be supported and shown in the dropdown when applicable.<br>
		<br>
		Values: 1 | 0 ( default ).</p>
		<dt>stylesheet
		<dd><p>The url of an external stylesheet to be applied to the editor.
		Rules defined in the stylesheet are used for rendering the HTML the editor produces.
		Classes defined in the stylesheet - those starting with a dot - are also used to populate the styles dropdown of the editor, so users can apply those styles to text fragments.</p>
		<p>Please note that css classes and id's starting with "ai" are used by the editor itself, so try to avoid naming your classes like that, unless you want to change the editor's appearance.
		Classes starting with "ai" will not be shown in the dropdown, but influence the editor's appearance.
		The <b>AIEditor</b> class controls the appearance of the editable document.  To set the default font and background color, use this class.</p>
		<dt>width
		<dd><p>The width of the editor.</p>
	</dl>
<hr><h1><a name="methods">METHODS</a></h1>
	<dl>
		<dt>append( name, value )
		<dd><p>This method allows you to add custom fields for saving along with the HTML that the editor generates.
		If the save method is "post", the fields will be appended as urlencoded fields to the http post.
		The 'xml' save method generates a list of elements with the given key as the element's name and the given value as the element's text.</p>
		<p>Note: the editor stores it's content in a form field named 'content' when posting a form, and in an element named 'content' when posting xml.
		Appending a key named 'content' may lead to undesirable results when trying to decode your post.</p>
		<dt>open()
		<dd><p>This method simulates the editor's open button.
		Apart from triggering the editor's <b>onopen</b> event,  This can be useful if you prefer to not to let the editor post its content itself, as you're using a custom form with other fields.</p>
		<p>The example below shows how to implement this:</p>
		<dt>save()
		<dd><p>This method makes it possible to simulate the editor's save button from script.
		This can be useful if you prefer to not to let the editor post its content itself, as you're using a custom form with other fields.</p>
		<p>The example below shows how to implement this:</p>
<pre>&lt;script&gt;
	aiEditor.onsave = fill_n_post;
	
	function fill_n_post( e ) {
		your_own_form.your_content.value = e.content;
		// other validation stuff goes here
		your_own_form.submit();
	}
&lt;/script&gt;
&lt;AI:aiEditor id="aiEditor" /&gt;
&lt;form id="your_own_form" method="post" action="your_own_url"&gt;
	[ your own form fields here ]
	&lt;input type="hidden" name="your_content"&gt;
	&lt;input type="button" value="send da stuff" onclick="aiEditor.save();"&gt;
&lt;/form&gt;
</pre>
	</dl>
<hr><h1><a name="events">EVENTS</a></h1>
	<dl>
		<dt>onbeforeload
		<dd><p>This event is generated just before content is loaded into the editor.
		The default editor behaviour is to load it's content from the content between the &lt;AI:aiEditor&gt; and &lt;/AI:aiEditor&gt; tags.</p>
		<p>Other built-in loading options can be activated by setting the <b>load_method</b> property to 'html' or 'xml'.</p>
		<p>For fine-grained control over the loading, set the <b>load_method</b> to 'custom', and write your loading routine as follows:</p>
<pre>
&lt;script language="javascript"&gt;
	onload = function() {
		aiEditor.onbeforeload = custom_loader;
	}
			
	function custom_loader( e ) {
		// your loading code here e.g.
		this.content = 'allyourbasearebelongtous';
	}
&lt/script&gt;
</pre>
		<p>Currently, the onbeforeload event does not contain any extra information, so it's not necessary to catch it in your event handler.
		The onbeforeload event is generated after the onload event of the containing document, so you can register your handler either in the window's onload handler,
		as in the example above, or somewhere else in your document, after you've written the aiEditor tag.</p>
		<dt>onopen
		<dd><p>This event is generated when the user presses the open button.
		For the default actions associated with this event, see the <b>open_method</b> property above.
		Catching this event allows you to fine-tune the way the editor loads a document.
		</p>
		<dt>onsave
		<dd><p>This event is generated when either the save button is pressed, or the component's save() method is called from script.
		The event has just one property, <b>content</b>, which holds the generated html.
		In order to get to the content, just place a script tag like this one, and replace the alert with something more meaningful:</p>
		<pre>&lt;script language="javascript"&gt;
	aiEditor.onsave = do_something;
			
	function do_something( e ) {
		alert( e.content );
	}
&lt/script&gt;</pre>
	</dl>
<hr><h1><a name="troubleshooting">TROUBLESHOOTING</a></h1>
<h2>Apache</h2>
<p>IIS 5.0 is preconfigured to recognize files with a .htc extension as hypertext components.
	Apache and other non-Microsoft web servers mostly aren't, and will send htc files as text/plain or text/html, or whatever is configured as the default MIME type.
	For Internet Explorer to execute the component correctly, it is essential that the web server should send the right Content-type header, which is <b>text/x-component</b>.</p>
<p>To make Apache send the right MIME type, try one of the following:</p>
<ul>
	<li>If you've access to your Apache configuration files, add the code below to the <i>httpd.conf</i> file.
	This file can be found in <i>/usr/local/httpd/conf/</i> for a standard Apache installation, or in <i>/etc/httpd/conf/</i> if you installed it together with RedHat.  If not, try <i>locate httpd.conf</i>.
	After this, you'll have to restart Apache.  Another way to add a MIME type would be to edit your <i>.../conf/mime.types</i> file.</li>
	<pre>AddType text/x-component htc</pre>
	<li>If you haven't access to your web server's configuration, you can include the line above in an access file.
	Typically, those are named <i>.htaccess</i>.
	This method isn't as efficient as the first one, as .htaccess files are parsed on each and every request, thus incurring a significant performance penalty.
	</li>
</ul>
<p>If this doesn't solve your problem instantly, don't panic!
	Although the MIME type is sent correctly by the web server, Internet Explorer will keep a cached copy of the document, even if your settings tell it never to cache files.
	To clear your cache, choose <i>Tools -> Internet Options... -> Delete Files</i>.</p>
<p>If the above doesn't work, it's time to post a plea on the support forum ;-).</p>
<h2>PHP</h2>
<p>If you embed the editor within PHP page, chances are that you'll get a PHP error like <i>PARSE ERROR, unexpected T-STRING at...</i>.
	This problem occurs if the short tags notation of PHP is enabled, allowing you to use the <i><? ?></i> notation for PHP script tags.
	Unfortunately the <i><?import /></i> directive necessary to embed the component will also be parsed as code, thus producing the error above.</p>
<p>To solve this problem, you'll have to rewrite the import tag as follows:</p>
<pre>&lt;? echo '&lt;' . '?import namespace="AI" implementation="aiEditor.htc" /&gt;' ?&gt;</pre>
<p>Even more of a bother is the fact that some servers seem to parse html and other files as PHP as well, so you'll have to rewrite the import statement in the same way in the aiTable.html, aiImage.html and aiLink.html files as well.</p>
<h2>IE security settings</h2>
<p>The settings for the content zone in which the editor is run have to allow the execution of ActiveX controls and script.
	To check this, open Tools -> Internet Options -> Security -> Custom Level... and check that the following items are set to <b>enable</b>:</p>
<p>ActiveX controls and plug-ins</p>
<ul>
	<li>Run ActiveX controls and plug-ins
	<li>Script ActiveX controls marked safe for scripting
</ul>
<p>Scripting</p>
<ul>
	<li>Active Scripting
</ul>
<p>The settings above are enabled by default in the medium and medium-low security settings, which are the defaults for respectively
	the internet zone and intranet zone of IE.</p>
<p>The file upload component makes use of the ADO Stream object to read the local file before uploading it.
	IE medium security settings do not allow access to a file from a different domain without prompting.
	Thus, it's probable that you'll get a prompt like <i>"Microsoft ADO/RDS - This page is accessing a data source on another domain. Do you want to allow this?"</i>.
	In order to avoid this prompt, either add the site to the trusted security zone, which permits access to other domains,
	or set the following security setting to <b>enable</b>:
<p>Miscellaneous</p>
<ul>
	<li>Access data sources across domains
</ul>
<hr><h1><a name="todo">TO DO</a></h1>
<ul>
	<li>add a better interface for the tables, so table cells can be merged.</li>
	<li>add a picker for special characters such as &amp;nbsp;.</li>
	<li>add samples for use with php and Perl/CGI.</li>
	<li>add support for nested css classes in the styles dropdown.</li>
	<li>bug: the emoticonpicker and colorpicker disappear when a control is selected on the document.</li>
</ul>
<hr><h1><a name="author">AUTHOR</a></h1>
<p>Original developer: Denis Braet &lt;<a href="mailto:denis.braet@aine.be">denis.braet@aine.be</a>&gt;</p>
<hr><h1><a name="homepage">HOMEPAGE</a></h1>
<p>The aynHTML project is hosted at <a href="sourceforge.net">SourceForge.net</a>.</p>
<p>The project's homepage is <a href="http://aynhtml.sourceforge.net">http://aynhtml.sourceforge.net</a>.
Visit this page for demo's and announcements.</p>
<p>Please visit <a href="http://sourceforge.net/projects/aynhtml/">http://sourceforge.net/projects/aynhtml/</a>
for the latest release, updates and bug fixes.</p>
<hr><h1><a name="copyleft">COPYLEFT</a></h1>
<p>aynHTML Editor :: wysiwyg HTML editor for IE5.5+</p>
<p>Copyright &copy; 2002-2003, Denis Braet. &lt;<a href="mailto:denis.braet@aine.be">denis.braet@aine.be</a>&gt;</p>
<p>This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.</p>
<p>This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.</p>
<p>You should have received a copy of the GNU General Public License
    along with this program; if not, a copy can be obtained at:</p>
<p><a href="http://http://www.gnu.org/licenses/gpl.html">http://http://www.gnu.org/licenses/gpl.html</a></p>
<hr>
</body>
</html>
